Script Inserter 1.0
by Griffin Knodle, a.k.a. Jair, 10/30/98
E-mail:gknodle@trinity.edu
http://fly.to/vale


---------------------------------------------------------------------------
WHAT IT IS
---------------------------------------------------------------------------
Script Inserter takes text from an ordinary text file, converts it using a table file, and re-inserts it into a ROM, changing the game's text.  It can automatically insert line, section, and message breaks for you.  It can even rewrite the pointer table for you, but this feature is quite jury-rigged right now, so don't count on it working with every ROM.  SI does not support automatic dual tile encoding or automatic text compression, but future versions may.  (You can do it manually, but it'll be a pain, and it probably won't be as efficient as it could be.)


---------------------------------------------------------------------------
WHAT YOU'LL NEED
---------------------------------------------------------------------------
A text file to insert
A table file for converting ordinary text into ROM text
A ROM to insert the text back into


---------------------------------------------------------------------------
WHAT TO DO
---------------------------------------------------------------------------
1. Basic program use
2. Table files
     a. Standard conversions -- "xx=whatever", "xxxx=whatever"
     b. Line, section, and message breaks -- "m: xx" or "/xx"
     c. Commands for Script Extractor
          1. Treatment of unconvertable bytes -- "?0", "?1", "?2"
          2. Style for converting break characters -- "?break: x"
          3. Length limits -- "?line: x", "?sect: x", "?msg: x"
          4. Pointer table location -- "?ptr table: xxxxxxxx"
          5. Overwrite / append to output file -- "?a"
     d. Displaying program control characters -- "prog cont char: xx=label"
     e. Index
3. A final word

---------------------------------------------------------------------------
1.  Basic program use
---------------------------------------------------------------------------
Run the program.  It will ask you what your table file is called.  (If you're a lazy typer like me, you don't have to type the ".tbl" extension -- it'll put it on for you.)  It will read the table file and warn you if it couldn't understand some of the entries.  Then it will ask you what text file you're reading from and what ROM you want to write to.  (If you just hit return, it'll assume that the files have the same name -- that is, if you type "zelda2.tbl", it will assume you're also using "zelda.txt" and "zelda2.nes".  I'm a lazy typer.)

Next it will ask for the address to start inserting at.  Then it will convert the text, but it won't change the ROM yet.  First, it asks whether it's OK to overwrite however many bytes the text came out to.  You must be careful not to overwrite too much of the ROM.  If you write past the end of the original text block, you may overwrite some program code and screw up the ROM.  If the insertion is going to be too long, type "n" to abort.  Otherwise, SI will insert the text and rewrite the pointer table (if you told it to in your table file).

---------------------------------------------------------------------------
2.  Table files
---------------------------------------------------------------------------
Script Inserter needs a table file to tell it how to convert each character you can read and edit into a byte for the ROM.  Basically, a table file looks like this:

58=A
59=B
5A=C
5B=D
A0=.
A1=!

Note that all values are given in hexadecimal (base 16).  This is how they'll show up if you're looking through the ROM in a hex editor such as Hex Workshop or Thingy.

---------------------------------------------------------------------------
2.a.  Standard conversions
---------------------------------------------------------------------------
The example above tells Script Inserter that a value of 58 hex represents "A", 59 represents "B", A1 represents "!", and so on.  Just put the value to convert to on the left, an equals sign, and what you want to convert from on the right.  You can have more than one letter on the right side.  You can also convert two bytes at once.  For example, these are all perfectly good entries:

AA=a
AB=b
C3=he
0400=Cecil

Note that longer strings take precedence over shorter strings.  For example, your table might include

F1=castle
A4=ca
2C=c

SI will first try to match "castle", then "ca", and finally it will settle for "c".

---------------------------------------------------------------------------
2.b.  Line, section, and message breaks
---------------------------------------------------------------------------
Most ROMs have certain values that represent line breaks, section breaks, or message breaks.  (Not all ROMs use all three kinds of breaks.)  A line break just drops down to the next line.  A section break waits for the player to push a button before continuing with the next section.  A message break stops displaying text and returns to the main game.

Hi, here comes a line [line break]
break. Soon we'll have [line break]
a section break. [section break]
Now I'm talking again. [line break]
But now I'm about to stop. [message break]
Hi!  This is a different [line break]
message, at a totally [line break]
different point in the game! [message break]

I hope that clears it up.  Anyhow, you represent these with "l: xx", "s: xx", and "m: xx", respectively.  If your ROM's line breaks are F0 and its message breaks are F1, your table file would include these two lines:

l: F0
m: F1

(The required elements are the first letter, the colon, and the value.  These two lines are the same as the above example:)

line break: F0
Message breaks are so cool! :F1

Oh, and some games, like Dragon Warrior 1, seem to use two bytes for breaks.  SI 1.0 supports this.

sect: FBFD

If your table files are for Necrosaro's Thingy, don't worry.  Script Inserter can also use Thingy's format (line breaks are "*xx", message breaks are "/xx").

---------------------------------------------------------------------------
2.c.  Commands for Script Inserter
---------------------------------------------------------------------------
Tables can have lines that don't convert any text, but instead give instructions to Script Inserter.  These command lines all begin with a question mark.

---------------------------------------------------------------------------
2.c.1.  Treatment of unconvertable bytes
---------------------------------------------------------------------------
Used only by Script Extractor.

---------------------------------------------------------------------------
2.c.2.  Style for converting break characters
---------------------------------------------------------------------------
If you're reinserting a script, then you already know about this.  One important thing: Make sure your script's format is what SI is expecting to find (because of the "?b" line in your table).  In short, just use the same table for your insertion as you did for your extraction and you'll be fine.

---------------------------------------------------------------------------
2.c.3.  Length limits
---------------------------------------------------------------------------
You can do your line, section, and message breaks manually, or you can set limits and let SI do them for you.  For instance, in Zelda 2, each line can be up to 11 characters long, and each message can be up to 4 lines.  I set these limits with these two lines:

?l: 11
?m: 4

Important: line length is in characters; section and message length are in lines.  SI will turn spaces into break characters as needed to keep each line, section, and message within the length limits.  Oh, and if a message overruns its size limit (which is easy to do in Zelda 2), SI will warn you and ignore the excess text (since it would screw everything up to add another message).

Be careful not to confuse the commands "?line length: x", "?sect length: x", and "?msg length: x" with the conversion instructions "line: xx", "sect: xx", and "msg: xx" (see 2.b).

---------------------------------------------------------------------------
2.c.4.  Pointer table address
---------------------------------------------------------------------------
Some games, like Dragon Warrior 1 and Final Fantasy 1, find a certain message by counting until they find the one they want.  These ROMs are easy to hack; you can just change the text and the game will work it out.  However, other games use pointer tables, which hold the starting address of each message.  In these ROMs, if you change message lengths you also have to change the pointers.

Fear not, though, because SI can rewrite pointer tables for you.  Major warning: This feature is jury-rigged right now, because ROMs use many different memory layouts.  It works on Zelda 2 and Radia, if nothing else.  In short, be warned that it's liable to fail.

Anyhow, you activate this feature by telling SI where the pointer table is.  (Future versions may find it for you.)  If you need to know how to find pointer tables, get the Relative Searcher Tutorial off my site.  Then put a line in your table like this (from Zelda 2):

?p: EFCE

Be careful not to confuse the "?ptr tbl: xxxxxxxx" command with the "prog cont char: xx=..." conversion instruction (2.d).

---------------------------------------------------------------------------
2.c.5.  Overwrite / append to output file
---------------------------------------------------------------------------
Used by Script Extractor.

---------------------------------------------------------------------------
2.d.  Displaying program-control characters
---------------------------------------------------------------------------
If you're inserting a script and this is important, then you already know what these are.  Again, just use the same table file as you used for the extraction, and SI will convert these back just fine.  And if you add some program control characters to your script, make sure you type them right.  That is, if your table has this:

prog cont char: 04=Name

then this will work fine:

Hey, <Name 00>, come here!

but this will be unconvertable:

Hey, <nam 00>, come here!

---------------------------------------------------------------------------
2.e.  Index
---------------------------------------------------------------------------
?0                        Treatment of unconvertable bytes   2.c.1
?1                        Treatment of unconvertable bytes   2.c.1
?2                        Treatment of unconvertable bytes   2.c.1
?append                   Append to output file              2.c.5
?break: x                 Style of output                    2.c.2
?line: x                  Sets maximum length for lines      2.c.3
?msg: x                   Sets maximum length for messages   2.c.3
?pointer table: xxxxxxxx  Gives pointer table's address      2.c.4
?sect: x                  Sets maximum length for sections   2.c.3
*xx                       Line break                         2.b
/xx                       Message break                      2.b
line: xx                  Line break                         2.b
msg: xx                   Message break                      2.b
prog cont char: xx=...    Program control character          2.d
sect: xx                  Section break                      2.b
xx=...                    Normal conversion                  2.a
xxxx=...                  Normal conversion, two bytes       2.a

---------------------------------------------------------------------------
3.  A final word
---------------------------------------------------------------------------
This probably seems pretty overwhelming.  There are example table files on my site you can download, look at, and use.  Keep an eye out for my detailed beginners' tutorial, coming sometime in the near future.  And as always, feel free to e-mail me with any questions, comments, or suggestions.


---------------------------------------------------------------------------
TERMS OF USE
---------------------------------------------------------------------------
This program is distributed with its source code.  You may use, distribute, and modify it freely.  Only two restrictions: These terms of use must stay the same, and you must always include the source code with the program.  Oh, and I'd appreciate it if you credit me as the original author.


---------------------------------------------------------------------------
DISCLAIMER
---------------------------------------------------------------------------
All games and systems mentioned are copyright their respective companies.  I am not responsible for any damage you may cause to your computer or software by using this program.  Owning a ROM is illegal unless you already own the cartridge.  If there are runners on first and second and fewer than two outs, a fly ball hit to an infielder shall be ruled "caught" even if the infielder drops it.  I think that about covers everything.

